Programming Sound Cards/Programming Sound Cards.iso/sound_45/readme

Text File | 1995-01-01 | 14KB | 355 lines

Mod Disassembler v 0.00

Introduction:

This program is used to dis-assemble a .mod file.  It creates a human
readable file describing everything in the .mod file.

It can optionally dump the samples in separate files in .wav or raw
format.  The wav and raw formats can be used by other sound editing
programs, and can easily be converted into other formats by conversion
utilities such as sox.

The dis-assembled mod file can be viewed or edited.  A companion program
modcomp can re-assemble the mod file.  (modcomp is not yet available as of
the date of this writing).  Mod_dis and modcomp can be used to compose
or modify mod files using any standard text editor, and can be used on
any machine, even those that cant play the files.

Mod_dis has been successfully compiled and tested on
    * unix - IRIX (SGI), SunOs 4.1.1 (Sun)
    * msdos

The source code is provided.  Other ports are encouraged.  Send me some
e-mail if you successfully port to a machine mot listed above.

The msdos executable is included for immediate use by those without
compilers.

The program is freely distributible provided the copyright notices
remain intact.

Usage: mod_dis [options] file.mod >file.dis
 options:
  -c n = set number of channels (aka voices, tracks) to n
  -i n = set number of instruments (aka samples) to n
      without -c and -i, mod_dis will attempt to figure out
      the file format
    Note: you normally do not need to set a -c or -i, however in
          rare circumstances where a mod file is known to be good,
          however has an unknown tag, you can try setting -c and -i
          to dis-assemble.

  -np = do not disassemble patterns
  -ns = do not disassemble samples
    Note: by default patterns and samples are dis-assembled.  However,
           if you want to just see some header information, you can
          specify -np -ns to give you a more compact file.

  -u  = unused patterns
      sometimes there are more patterns in the file than are actually used
      in the song.  By default these are ignored.  With the -u flag they are
      disassembled.

    Note: If you specify -np, you will not get any patterns dis-assembled.

  -v = verbose (another -v = more verbose)

    Note: Normally only errors are reported to the error output (your
          terminal).  -v will also report some internal program
          diagnostics as well as warnings.  -v -v will give you even
          more.

    Note:    Additional comments may be placed in the disassembled
        output when you use -v.

  -f x = format of samples, values of x are:
         i=internal, s=raw samples (.sam),
         a=ascii (.txt), w=Microsoft wave (.wav)
         w1=.wav at 11025 Hz

    Note:    -ns will override the -f flag.
    Note:    -f i is the default, causing sample values to be
        dumped in a textual format at the end of the
        dis-assembled output.  You can redirect the
        sample dump to another file by specifying one
        of the other -f switches.
    Note:    The name of the external file can be controlled
        with the -p switch.
    Note:    If there are more than one instrument in the source
        file (very likely), you will get multiple sample
        files.
    Note:    The .sam format is simply a stream of unsigned 8-bit
        values.
    Note:    The .wav file is encoded to play back at 16574 samples/sec.,
        which corresponds to the standard C-3 playback rate.  If your
        sound card or wav editor doesnt like this rate, you can
        use the -f w1 flag to create a .wav file which will
        play back at the standard 11025 Hz, the tone of the
        resultant sample will be lowered somewhat when played
        back, mod_dis does not adjust do any re-sampling to
        compensate.
    Note:    Some features of the instruments are not placed in
        the sample files, like finetune, repeats, volume, etc...
        Hence playback software is not likely to reproduce
        the same sound as the sample when played as part of the
        .mod file.
        However the standard .wav file will include an INFO block
        which will encode these values into the "comment" field.
        The modcomp software will make use of this specially
        formatted comment.
    Note:    It is not likely any of the other major sound file
        formats will be supported.  Thre are many tools which
        can convert to/from these formats.  However,
        I will make an effort to support any standard format which
        allows you to specify finetune, names, and loop points
        so that all of the sample information can be encoded.

  -p prefix = prefix of sample output files (defaults to inst)
  -s suffix = suffix of sample output files (override format default)

    Note:    Use the forward slash (/) to separate directories instead
        of the backward slash, even in MSDOS.
    Note:    -p and -s are only useful when the format is not
        internal.
    Note:    The name of the files created will be
            <prefix>nn<suffix>
        where nn is the sample # (0 thru 31 in most .mod files).
    Note:     When specifying a prefix, you can give a leading
        directory path.  Use the forward slash (/) to separate
        directories instead of the backward slash, even in MSDOS.
    Note:    Make sure you leave enough room to hold the extra 2 digits
        generated.  Some filesystems (namely MSDOS) have filename
        length limits.
    Note:    The suffix defaults as follows:
            -f w or -f w1    .wav
            -f s        .sam
            -f a        .txt

 file.mod = input file

    Note:    MED, S3M, STM, and other formats are not supported at
        this time.  This is mainly due to the lack of useable
        documentation on the file formats.  If you have some
        docs, you are welcomed to send them to me.

 file.dis = output file

    Note:    The output normally goes to the terminal unless you redirect
        it.
    Note:    Some mod files can generate dis-assemblies over 4 Mb. in
        size.  Use the -np and -ns, or -f options to limit the
        material written to the dis-assembly.
    Note:    Some text editors may fail to load very large dis-assemblies.
        Get a better editor.

Examples:

    mod_dis -v -f w -p abc abc.mod > abc.dis

    - dis-assemble abc.mod to abc.dis, samples will be written
      to abc0.wav, abc1.wav, etc...

    mod_dis -np -ns abc.mod > abc.dis

    - dis-assemble only the header information of abc.mod

Diagnostics:

    Generally speaking, if you get error messages, its likely that
    the .mod file is not in the standard mod format.  If you dont
    understand the error message, look at the documentation for
    mod file formats and the source code.

    mod_dis is fairly pessimistic when it finds something that is
    not standard.  Use the "-v -v" flag to see all the warnings.
    Due to the wide variety of Mod trackers in use, there are
    many interpretations of the mod format specification in popular
    programs.

    If you are absolutely sure your mod file is standard and contains
    no errors, send me some e-mail and I'll check it out.  It could
    well be that the program has bugs.

Disassembled mod output:

    The output is created in such a way as so it can be fed as input
    to the companion program "modcomp" to re-compile it into a .mod
    file.  The language specification is still evolving so whem
    modcomp is released, it is likely that an updated mod_dis will
    be released.  The output format may be changed slightly.

    The sample info (length, repeat offset, repeat length) is printed
    out in bytes.  This is the most portable.  The dummy amiga
    word is not included, only the real sample information.
    This avoids any confusion about whether to add or subtract, and
    converting from words to bytes.  Let modcomp do the work for you.

    It is common practice to have sample names which have nothing to
    do with the sample itself, sometimes even have a sample name
    for a sample with no data.  These are included in the disassembly.

    Sometimes non-ascii characters are used in sample names, presumably
    they display as interesting graphical characters on some machines.
    Those characters may or may not be put in the disassembly
    correctly, and may or may not display right in your text editor.
    It is an unportable use and is discouraged.  Future implementations
    may strip unportable characters.

    C++ style comments are sometimes placed in the output.  Modcomp
    will ignore everything from the // to the end-of-line.

Bugs:

    mod_dis does not like backslash (\) in the prefix or suffix (-p and
    -s command line options).  Use / when you mean \.

    mod_dis and modcomp will NOT play mod files - there are plenty
    of programs out there that do.

    Some mod formats not supported.  Without detailed documentation
    and standardization, they may never be supported.  Perhaps you can
    convert it to a standard mod format for dis-assembly.  I would like
    to see a standard format for unlimited sample size, 16 bit sample
    width, unlimited pattern length and table.  It ought to make better
    quality mods.

    mod_dis doesn't understand any of the compression techniques used
    to pack mod files.

    mod_dis will not operate on mod files in archives.

Files:
    The executable 'mod_dis.exe' is supplied, which is an executable
    for MSDOS.  For all other systems, you will need to compile from
    the sources.  The MSDOS executable is built using Microsoft
    Visual C++ 1.0, using the large memory model.

    The sources consist of misc.c, mod_dis.c, mod_disv.c, wav.h,
    wav.c, misc.h, modcomp.h.  makefile.unx is provided for unix
    systems, to compile just "make -f makefile.unx".

    Text files
    are provided in msdos text format, you will need to convert them
    to unix format for best results.  You can use this shell command:

        sed 's/^M//' < dos_text_file > unix_text_file
         (the ^M is a control-M, you may need to escape it with
          a backslash or control-V depending on the shell)

    mod_dis.mak is provided to use by the Microsoft Visual C++ 1.0
    compiler.  Use the .mak as the project file in the IDE, or
    on the command line you can "nmake -f mod_dis.mak".  I think
    debugging is enabled in the project.

    A sample mod file and dis-assembly is given as a reference
    example (taken from the Sound-Site CD-ROM).  It was generated
    using the shell command

        mod_dis -v -v drave.mod > drave.rpt 2> drave.err



Porting:

    There is generous use of casts to avoid warnings emitted by
    the Microsoft compiler.

    There is a lot of kludgey code in MSDOS because "int" is 16 bits.

    The program prefers an ANSI compliant compiler, but does compile
    using the sunos compiler.  (__STDC__ not defined).  It has
    not been tested on a Solaris compiler, or the GNU compiler.

    Look in the misc.h file, you want to make sure the correct endian-ness
    is set.  Also there are a bunch of stuff that depends on __MSDOS__
    being set, which may or may not need to be set if you use a compiler
    other than Microsoft.

    There is a function "verify_port()" in mod_dis.c, look over the
    code and make sure it runs properly for the machine you port to.

    There seems to be 2 schools of thought on the interpretation of
    the repeat length.  The macro RPT_LENGTH_IS_INCR defines which
    way the program defaults to.  As currently set, repeat length
    is interpreted as including the amiga dummy word.

Testing:
    mod_dis is tested on approx 1000 mod files taken from the AMINET
    archive.  Of the 1000 files, there are approx 630 standard mod
     format files (the rest predominently med, stm, packed).  Of the
    630 only 2 fail to disassemble.  I haven't looked in close detail
    at why.

    It has also been tested on 1365 mod files on the Sound-site
    CD-ROM - only 2 files there fail to disassemble.  ( There are
    other failures but they are legitimate, they were on files
    in the bad and corrupt directories.)

    The wav files generated have been tested on several .wav editors,
    and several .wav players playing on a SoundBlaster 16 on a PC
    running windows 3.1.  I've only found 1 program required the "-f w1"
    .wav files: Microsoft wavedit.exe - it didnt like the non-standard
    playback rate.

References:

    mod file format documentation, by THUNDER ([e-mail])
    Advanced Music Formats Document, By Jamal Hannah [e-mail]
    mod format info, by Lars Hamre <[e-mail]>
    RIFF WAVE (.WAV) file format, by Microsoft, transcribed by
        Rob Ryan <[e-mail]>


Special thanks to [e-mail] for answering many questions on mod file format.


/* BEGIN DAVID LAI COPYRIGHT ********************************************* */
/*
(C) Copyright David Lai 1993, 1994.  All rights reserved.

The source code is copyright by David Lai, however it is freely
distributable and released for unrestricted use.  Users may copy or modify
this source code without charge, provided all copyright
notices remain intact in all the source code.  Portions of the source code
copyright by their respective copyright holders and are covered
under different agreements, however the source code used has
specifically been marked distributable royalty-free.

You can do whatever you want with it, even charge money for it, if
you find a sucker willing to pay for it.  This is not shareware, the program
is not crippled in any way, do not send money.  You can e-mail comments
to the electronic mail address below, or fax to the fax number below.

If you add a feature thats useful, or do a new port, you can send
the context diffs to the e-mail address below.  I may include it in
subsequent releases.  Your code must specifically be marked
freely distributable, I will not include code marked otherwise.

THE SOURCE CODE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING
THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.

The source code is provided with no support and without any obligation on
the part of David Lai to assist in its use, correction,
modification or enhancement.

DAVID LAI SHALL HAVE NO LIABILITY WITH RESPECT TO THE
INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS SOFTWARE
OR ANY PART THEREOF.

In no event will David Lai be liable for any lost revenue
or profits or other special, indirect and consequential damages, even if
David Lai has been advised of the possibility of such damages.  Etc, etc,
blah, blah, blah...

David Lai
1370 McKendrie St
San Jose, CA 95126
fax: [phone]

[e-mail]

*/
/* END   DAVID LAI COPYRIGHT ********************************************* */